TrafficWatch on a server (no display)
=====================================

The desktop app needs a graphical session. This folder also ships a headless
mode that does not — it answers and records DNS queries exactly the same way,
and shows the same screen in your browser instead of a window.

Everything below quotes the install path: it contains a space.

What a minimal server still needs
---------------------------------
Headless mode opens no window and contacts no X server, but the program is one
binary and the system loads every library that binary is linked against before
it starts. So GTK, X11, NSS and ALSA have to be installed even though nothing
draws. The .deb package lists them as dependencies and apt installs them for
you. If they are missing anyway, trafficwatch-headless says so and prints the
apt / dnf line rather than leaving you with a bare "error while loading shared
libraries".

Try it in the foreground first
------------------------------
Port 53 is privileged, so a plain user cannot bind it. For a first look, use a
high port and the loopback address (no root needed):

    "/opt/Network TrafficWatch/trafficwatch-headless" --dns-port 5353 --dns-host 127.0.0.1

It prints the web UI address, including a one-time token:

    web UI   http://127.0.0.1:8053/?token=...

Open that address once; afterwards http://127.0.0.1:8053/ is enough (a cookie
remembers you). Send a query from the same machine to see it appear:

    dig @127.0.0.1 -p 5353 example.com

The screen's "Send a test query" button does the same thing from the browser.

Run it as a service (port 53)
-----------------------------
See trafficwatch-headless.service in this folder — the commands are at the top
of that file. Two things are specific to this product:

  * The unit keeps  AmbientCapabilities=CAP_NET_BIND_SERVICE  uncommented.
    That is what lets the service user open port 53. Do not remove it.

  * systemd-resolved on Ubuntu already holds 127.0.0.53:53, so binding every
    address fails with EADDRINUSE. The unit's ExecStart therefore passes
    --dns-host <LAN address>: edit that one address to this server's own
    (`ip -4 addr`), and the two coexist. The alternative — DNSStubListener=no
    in /etc/systemd/resolved.conf — also works but then the server's own
    /etc/resolv.conf needs attention.

Then point your router's DHCP DNS setting at that LAN address. Every device
that renews its lease starts sending its lookups here.

Options:          "/opt/Network TrafficWatch/trafficwatch-headless" --help
Lost the address: "/opt/Network TrafficWatch/trafficwatch-headless" --show-url

Reaching the UI from another machine
------------------------------------
By default the UI only listens on 127.0.0.1. Either tunnel to it:

    ssh -L 8053:127.0.0.1:8053 user@server        # then open http://127.0.0.1:8053/

or put an HTTPS reverse proxy (nginx, Caddy) in front and start with
--ui-host 127.0.0.1 --ui-port 8053 as before. Do not expose the plain HTTP
port to an untrusted network: every device's lookups, SMTP credentials and the
Central token pass through it.

Secrets on a server
-------------------
There is no keyring on a server, so the licence key, SMTP password and Central
token are stored as plain files readable only by the service user (mode 0600)
under the data folder.

Notifications
-------------
There is no desktop to notify. A rule that would have raised a desktop
notification writes one line to the journal instead (journalctl -u
trafficwatch-headless). E-mail alerts and MeshWatch Central work as on the
desktop — Central is the intended alert path for a server.

Where the data is — and the licence key
---------------------------------------
The data folder is ~/.trafficwatch of the user that runs it (or
TRAFFICWATCH_DATA_DIR). As a service that is /var/lib/trafficwatch/.trafficwatch.

If you ran the Linux desktop app with sudo (the README's route to port 53), its
data is in /root/.trafficwatch — a different folder from the service's. The
licence key is therefore not shared automatically: paste it again in the web UI
(plan badge in the title bar). The same key may be active in both places.
